The XML for a Record Template

Tip: See Example Record Templates for examples of Record Templates along with an explanation of how they are constructed.

Before defining the XML tags and examining how to specify a Record Template, here is a quick summary of the XML structure used by the three kinds of fields in EMu:

An atomic field contains a single value. It is represented by a single data entry area in the EMu client. The XML snippet used to represent an atomic value is:

   <atom name="colname">value</atom>

where:

colname is the back-end name of the field.
value is the contents of the field.

A nested table field contains a list of values. A grid is used to display the list in the EMu client. The XML format for a nested table is:

<table name="colname">
   <tuple>
      <atom>value 1</atom>
   </tuple>
   <tuple>
      <atom>value 2</atom>
   </tuple>
   ...
</table>

where:

colname is the back-end name of the field.
value 1, value 2, etc. are the values in the list.

There is no limit to the number of <tuple> entries in a nested table.

A double nested table field consists of a list where each entry is itself a list. The EMu client uses the nested form construct (where a grid at the bottom of the tab controls what data is shown) where a grid is displayed in the top part of the tab. The XML required for a double nested table is:

<table name="colname">
	<tuple>
		<table>
			<tuple>
				<atom>value 1-1</atom>
			</tuple>
			<tuple>
				<atom>value 1-2</atom>
			</tuple>
			...
		</table>
	</tuple>
	<tuple>
		<table>
			<tuple>
				<atom>value 2-1</atom>
			</tuple>
			...
		</table>
	</tuple>
	...
</table>

where:

colname is the back-end name of the field.
value 1-1, value 1-2, etc. are the list of values in the first list.
value 2-1, value 2-2, etc. are the list of values in the second list and so on.

There is no limit to the number of values in any of the lists.

When specifying a record the three kinds of field are enclosed within <tuple></tuple> tags. Let's consider an example in which we are to encode the data in the following Parties record:

Parties record

The XML below represents the data entered by a user and does not include computed values (found in the Derived Names group box when Automatic is set to Yes):

<tuple>
	<atom name="NamPartyType">Person</atom>
	<atom name="NamTitle">Dr</atom>
	<atom name="NamFirst">Charles</atom>
	<atom name="NamMiddle">Jim</atom>
	<atom name="NamLast">Marshall</atom>
	<table name="NamOtherNames_tab">
		<tuple>
			<atom>Charlie</atom>
		</tuple>
		<tuple>
			<atom>Chuck</atom>
		</tuple>
	</table>
	<atom name="NamSex">Male</atom>
	<atom name="NamAutomatic">Yes</atom>
</tuple>

Fields that do not contain a value are not specified. You may include empty values if you want to remove any data already in the field (e.g. a Default value added when a new record is added). An empty value consists of a tag of the form:

<atom name="colname"/>

The description of a Record Template is an XML document. Its complete structure is given here:

Tip: See XML Tags defined below for an explanation of each of the tags used.

There are comments and instructions in the code below, included as: <!-- Comment / Instruction -->. Note that these may require that you add / repeat code.

  • Anything in italics needs to be replaced with the correct value, e.g. a column name, number, etc.:

    For example:

    <source name="colname" rows="rowlist" nestedrows="rowlist"/>

    might be:

    <source name="MulCreator_tab" rows="1"/>

  • As you can see in the previous point, you may not need to include all values (in the previous example only name= and rows= is required; nestedrows= is omitted).

<template maxrecord="number" setIRN="yes|no">

<tuple>

<atom name="colname"> <!-- Atomic value: add atomic values as required -->

text

<source name="colname" rows="rowlist" nestedrows="rowlist"/>

<input type="text|integer|float" cols="number" rows="number" increment="number" mandatory="yes|no">

<prompt>

text

<source name="colname" rows="rowlist" nestedrows="rowlist"/>

</prompt>

<help>

text

<source name="colname" rows="rowlist" nestedrows="rowlist"/>

</help>

<value>

text

<source name="colname" rows="rowlist" nestedrows="rowlist"/>

</value>

</input>

<records/>

<number/>

</atom>

<table name="colname"> <!-- Nested or double nested table - add tables as required -->

<tuple> <!-- nested table - repeatable -->

<atom>

<!-- Add code as for atom above -->

</atom>

</tuple>

<tuple> <!-- Double nested table - add as required-->

<table>

<source name="colname" rows="rowlist" nestedrows="rowlist"/>

<tuple> <!-- Nested table - add as required-->

<atom>

<!-- Add code as for atom above -->

</atom>

</tuple>

</table>

</tuple>

<source name="colname" rows="rowlist" nestedrows="rowlist"/>

</table>

</tuple>

<report>

text

<column name="colname"/>

</report>

</template>

Although the XML may look complex, the main part is the specification of the fields that require values to be set. The format of the XML for this part is exactly the same as that generated by the EMu XML Export facility, which is the same as that used by the EMu XML Import tool. Using this same structure means a skeletal XML record can be generated by building a report with the required fields and producing an XML Export file. Once you have the skeletal XML it can be expanded to include any additional options required.

Each of the tags used in the complete structure of an XML document is described here:

The <template> tag encloses the Record Template XML description. It must be the first tag, and the corresponding closing tag </template> must be the last tag. Attributes associated with the tag represent options available when the template is used.

Attributes

maxrecords

Specifies the maximum number of records that may be generated using this Template. If a number is given, a hint is displayed next to the Number of records to create input text box. If the attribute is not specified, no limit exists on the number of records that can be created.

setIRN

Indicates whether a starting IRN may be entered when the Record Template is used. If a value of no is supplied, the Starting IRN prompt and input box are removed from the Record Template Records screen. The default value is yes.

Contains

<tuple>

<report>

Contained within

none

The first line of the XML is used to configure the first screen of the Record Template wizard:

Record Templates

This example screen is specified as:

<template maxrecord="10" setIRN="Yes">

The following screen is specified as:

<template maxrecord="20" setIRN="No">

Record Templates

The following screen is specified as:

<template>

Record Templates

The <source> tag extracts information from the source record (the current record). The tag is replaced with the value(s) extracted. Data can be extracted from any field kind (atomic, nested table and double nested table) into any field kind. Where a mismatch between the field kinds occurs the data is either converted to a newline separated value (when going from a table to an atomic field) or wrapped in table XML (when going from an atomic value to a table). Using attributes it is possible to extract parts of tables or double nested tables.

Attributes

name

Specifies the name of the column from which the value is to be extracted. The name attribute is mandatory.

rows

Contains a list of numbers indicating which rows should be extracted from a nested table. The list is a comma separated set of numbers or ranges. An example list setting is rows="1,3-5,7-", which indicates that rows one, three to five and seven onward are to be extracted. If this attribute is not specified, all rows are extracted.

nestedrows

Contains a list of rows indicating which of the outer rows in a double nested table are to be extracted. The format of the row list is the same as for the rows attribute. The rows attribute is used to specify the inner row numbers to be extracted. The default is to extract all nested rows.

Contains

None

Contained within

<table>
<atom>
<prompt>
<help>
<value>

The <input> tag indicates that the user should be asked to enter a value when the Record Template is used. The tag is replaced with the value entered. Each <input> tag found in the Record Template description produces an Input Values screen when the Template is used.

Attributes

type

Defines the type of data the user may enter. The available types are:

  • text
  • integer
  • float

When the user moves out of the input text box a check is made to ensure a legal value has been input. The default type is text.

cols

Indicates the width in characters of the input box displayed on the Input Values screen when the Template is used. The number does not limit the length of the value that may be entered. The default is 8.

rows

Specifies the number of rows the input text box should display on the Input Values screen when the Template is used. Users may enter more lines than the number specified. The default is 1.

increment

Indicates that the value entered should be incremented by the increment amount after each record is created. For example, setting increment="1" would increase the value entered by the user by one for every record created.

mandatory

Determines whether an input value must be specified. A value of no indicates an empty value is acceptable, while yes ensures that a value is entered. The default value is yes.

Contains

<prompt>
<help>
<value>

Contained within

<atom>

The <prompt> tag appears within an <input> tag and defines the prompt displayed on the Input Values screen. The default prompt is Input value.

Attributes

None

Contains

text

<source>

Contained within

<input>

The <help> tag appears within an <input> tag and specifies a help message displayed below the input text box on the Input Values screen. If a help tag is not defined, a help message is not displayed.

Attributes

None

Contains

text

<source>

Contained within

<input>

The <value> tag appears within an <input> tag and contains the initial value shown in the input text box on the Input Values screen. If a value is not specified, the input text box will be empty.

Attributes

None

Contains

text

<source>

Contained within

<input>

The <records> tag is replaced with the number of records to be created.

Attributes

None

Contains

None

Contained within

<atom>

The <number> tag is replaced with the number of the record being created.

Attributes

None

Contains

None

Contained within

<atom>

The <report> tag defines the text to be displayed for each record created in the Record Template report file. The text defined should identify the record created uniquely (e.g. Registration Number).

Attributes

None

Contains

text

<column>

Contained within

<template>

The <column> tag is replaced with the value in the specified column name in the created record.

Attributes

name

Specifies the name of the column from which the value is to be extracted. The name attribute is mandatory.

Contains

none

Contained within

<report>